package Arcos::JobQueue::Handler;

use strict;
use warnings;

sub graceful_shutdown {

    # do nothing by default
}

sub post_shutdown {

    # do nothing by default
}

1;

__END__

=head1 NAME

Arcos::JobQueue::Handler - API for handling jobs in the queue

=head1 SYNOPSIS

    sub handler {
        my ($class, %params) = @_;
        my %result = some_task_using_params(\%params);        
        return \%result;
    }
    
    sub graceful_shutdown {
        my $class = shift;
        my %args =
            validate(@_,
                    {job_id => 1,
                     pid    => 1,
                    });
     
     # do something with job_id and pid
    }
    
    sub post_shutdown {
        # same parameters as graceful_shutdown
    }

=head1 DESCRIPTION

This is the API for handling jobs in the job queue.  The gist is to implement 
a method called C<handler> and add your class and job type to 
F<conf/queue.conf>.  Details of the input and output are below.

=head1 INTERFACE

=over 4

=item C<handler(%params)>

This is a class method which gets called by the job queue daemon.  It will be 
passed the hash of parameters that were submitted for this job, plus an added 
key of C<job_id>.  (These are passed as a hash and not a reference so that 
you can more easily use C<Params::Validate> to check them, so please do.)

The return from this method should be a reference to a hash, which will be 
serialized with C<Storable> and can be retrieved by clients.  If you don't want
to return anything, you can just return undef.

=item C<graceful_shutdown(job_id => $Job_id, pid => $pid)>

This hook is called by the job queue daemon when it does a graceful shutdown.  This is an opportunity for handlers which implement long-running jobs to do something to pause these jobs.  For example, the mailing handler uses the mailing pause feature here.

=item C<post_shutdown(job_id => $Job_id, pid => $pid)>

This hook is called by the job queue daemon after a graceful shutdown, when the child processes have all exited.  This is an opportunity to flag jobs that were paused so they can be resumed.  For example, the mailing handler submits a restart job for any mailings it paused here.

=back

=head1 SEE ALSO

L<Arcos::JobQueue::Daemon>, L<Arcos::DB::ContributionProcessor>
